/*
 * Copyright 2025 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.compose.runtime.annotation

/**
 * Annotates that a class should not be retained. Types annotated with [DoNotRetain] should not be
 * used in the return type of the `calculation` lambda given to the `retain {}` method in
 * `androidx.compose.runtime`, or as a key input to `retain`.
 *
 * When present on a class, a lint error will be reported when the class or any of its subclasses
 * appear as the generic type of a call to `retain` or as a `key` parameter. The associated
 * inspection only checks the direct return type of the `calculation` lambda, but retained values
 * should hold no strong references, direct or indirect, to any type marked as [DoNotRetain].
 *
 * Generally, this annotation is expected to be used on resources that will be leaked if they are
 * retained. Additional or other rationale may be provided by specifying an [explanation], which
 * will appear in the lint error message when applicable.
 */
@MustBeDocumented
@Retention(AnnotationRetention.BINARY)
@Target(AnnotationTarget.CLASS)
public annotation class DoNotRetain(
    /**
     * An optional explanation of why this class should not be retained. If this value is not an
     * empty string, it will be presented in the error description at the callsite of offending
     * usages of this type.
     */
    val explanation: String = ""
)
